Project reports provide metadata about a project. This information answers questions like these:

• What is the test coverage?
• How well does the code adhere to the given coding standards?
• By which parameters has the project been built?
• What has been changed since the last release?
• What is the meaning of error codes issued by the library/application?
• By what properties can the library/application be configured?

The answers provide transparency to users of the project.

Attaching Metadata

Report information rendered in a project site makes it easily readable for humans. If you want to use some of this data in your build process, an easily parsable format would be much more convenient than grabbing the information from an HTML page. If the metadata is attached like a Maven site and stored in the artifact repository, writing plugins that read and display this information would be very comfortable. It also allows to mashup figures from different reports, even different projects, and draw new conclusions.

Aggregation Reports

In a multi project configuration Maven already allows to aggregate reports. This is useful since questions about quality metrics are often directed to the whole project and not only to its parts. There should be one report on code coverage to consult with no need to traverse the submodules individually.

What is true for a multi project configuration is also true for a more loosely coupled project spanning multiple individual projects. This is either necessary, since each project has its own lifecycle, or just convenient, because loosely coupled projects follow the delivery pipeline principle (please refer to Jez Humble in Continuous Delivery: Anatomy of the Deployment Pipeline) easily:

Loosely coupled projects help to reduce the complexity and increase the speed of release builds. If the release of a large project can be built on top of released sub projects, the release is much easier to handle. The drawback is that you have to deal with releasing multiple projects before you are able to release your whole product. Running a release must be reduced to a non-event to handle this appropriately.

Support by Maven Reports

While some Maven plugins, like the Maven Javadoc Plugin provide means to create an aggregate report for projects that are not part of a multi module build (please refer to Aggregating Javadocs from Dependency Sources for details), some reports don’t. For some reports it would be easy to merge report data. An issues report may merge issues marked as ‘new-and-noteworthy’ into a global new and noteworthy report. Other reports may need to be restructured to run on pre-generated report results.

Maven Plugin to attach Metadata

The next step is to make this information available with the semantic web. Until then, the Projectmetadata Maven Plugin allows to gather project metadata and make it accessible due to attached project artifacts.

The initial release of smartics Properties has been published! The version tag is 0.1.0, since this is the first release of a project that is based on our smartics Exceptions, but features a bunch of new concepts.

(Do not be confused if the minor number has already changed, since we continuously update the documentation. :-))

This post introduces the basic concepts of this project.

Declaration of Properties

The declaration of properties is modern and much simpler than in the old days. Simply write a Java interface and add the @PropertySet annotation.

@PropertySet("my")
public interface MyProperties {
  String myString();
  URL myUrl();
  List<String> myList();
  MyCustomType myCustomType();
}

With its declaration a property type, constraints and metadata is determined.

Definition of Properties

Providing a value for a declared property is called definition of a property. This can be done in a couple of ways like a simple properties file on the classpath or in a folder on the file system. Or it may be stored in a database or other sort of backend information system.

The definition of the properties declared above in a properties file may look like this:

my.myString=Hello Properties!
my.myUrl=http://www.maycorporation.com/index.html
my.myList=one, two, three
my.myCustomType=purple:123

Please note that the name of the property set (my) is required as a prefix.

Accessing Properties

It is important that the way properties are accessed is independent of how the properties are defined. Therefore an implementation provides a factory that is able to create configurations. A configuration is a set of property sets. Each property set is a collection of properties. While a configuration is specific to an environment and maybe an application within that environment, a property set is not.

It is an implementation detail how a factory is configured to be able to provide configurations to its clients (please refer to the library’s homepage for details – e.g. One-String-Property Tutorial for an implementation that provides access to properties deployed on the classpath).

final ConfigurationPropertiesFactory factory =
    ConfigurationPropertiesFactoryFactory.createDefaultFactory();

final ConfigurationPropertiesManagement config =
    factory.createDefaultManagement();

The code above creates a default configuration.

The following code snippet shows how to access properties:

final MyProperties properties =
  config.getProperties(MyProperties .class);
final String myString = properties.myString();
final URL myUrl = properties.myUrl();
final List<String> myList = properties.myList();
final MyCustomType  myCustomType = properties.myCustomType();

You will find more information on the project’s site, especially on the tutorial pages and the smartics Properties Maven Plugin for integration with Maven.

If you have questions or comments, please do not hesitate to leave a comment or drop us a line!

There is always the need for good documentation if a system or API lacks intuitive handling. For simple tasks this should never be the case, but to accomplish more complex tasks this is often necessary. Documentation is not only the printed manual, it is also context sensitive help that leads to an information system with additional advice for the task at hand. In whatever form the documentation is presented, there are some common attributes a good documentation requires. Two of them are correctness and being up-to-date. Let’s focus on the need of documentation for a software product being up-to-date with the implementation, since being out-of-date implies that the information is no longer correct. How can this be accomplished?

Living Documentation

One answer is given by Gojko Adzic in his book Specification by Example: Living Documentation. What is living documentation?

Living documentation is a source of information about system functionality that’s as reliable as programming language code but much easier to access and understand.

Gojko Adzic

Behavior Driven Development Tools

That opens a wide spectrum of technologies. One set of tools are found in the world of behavior driven development (BDD) (for more information on BDD please refer to “Introducing BDD” by Dan North), e.g. Cucumber or JBehave (please refer to Resources on the Specification by Example’s website for a list of additional tools). These tools make specifications executable and allow to gain more transparency on what the code does compared to what it was designed to do. If there is a discrepancy, these tools will tell immediately.

Reports

But BDD tools are not the only utilities that support living documentation. Gojko Adzic names one problem in today’s software development process that is addressed by the living documentation approach:

Code is often the only thing we can really trust; most written documentation is outdated before the project is delivered. Gojko Adzic

Robert C. Martin states another in his book Clean Code:

The older a comment is, and the farther away it is from the code it describes, the more likely it is to be just plain wrong.

Robert C. Martin

And he comes to the conclusion:

Comments are, at best, a necessary evil.

Robert C. Martin

We argue that a comment is a form of documentation that relates to an implementation detail. So we can rephrase the cites of Robert C. Martin to:

This is true for everyday’s devices like mobile phones. A documentation delivered with the device may be out of date after the first software update and as a user we do not want to have to consult a manual prior to enjoying its services. This is also true for software documentation. A document, especially written with a tool designed for creating slides or letters, will loose its benefit over time (as the burden of maintaining the document consumes scarce resources and details may evade the maintainer’s eye) until it does more harm than good (at the time it is out of date and its information is no longer correct). It would be honest to admit that such a document is created only to preserve a snapshot on information about the software, as soon as the burden of maintenance is greater than its benefit as a source of correct information.

Generating Reports

The cites of Gojko Adzic and Robert C. Martin direct us to the conclusion that we want our documentation to be as minimal and as next to the code as possible. Therefore it is useful to create reports that make the information in the code more accessible and easier to understand. We have released a set of tools that do exactly this (and are continuously working on the improvement of these tools):

• smartics-testdoc-tools – visualization of tests as stories, similar to the goals of agiledox, written by Chris Stevenson back in 2003.
• smartics Properties – provides a library to use properties and generate a documentation within a Maven project site.
• smartics Exceptions – provides a library to use exceptions and document the meaning of exception codes.

These projects have in common that they analyse (test and production) code and generate reports. They help to synchronize the implementation with the documentation at no additional cost (besides configuration of the tools and adding a few metadata to the code). If the code is changed, the documentation is updated automatically. The tools allow developers to comment their work and make this documentation also visible to non-coders. For many projects this information is enough. For projects having requirements such as multilingual documentation or documentation that is written by a technical writer, these reports can be used as a foundation for this additional work.

Screenshots of Reports

Here is an example on a testdoc report generated by smartics-testdoc-tools:

This an example of a report on properties generated by smartics Properties:

This an example on a report on exception codes generated by smartics Exceptions:

If you are interested how to use these tools in your project, please consult the project’s sites: